home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 November / EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso / earcd / misc / savename.lha / SaveNames1.3 / SaveNames.doc < prev    next >
Text File  |  1995-09-30  |  12KB  |  285 lines
  1.  
  2.  Copyright (why not...)
  3.  ----------------------
  4.  
  5.  SaveNames v1.3 software and documentation are copyrighted © 1995 by
  6.  Marcin Orlowski. All Rights Reserved.
  7.  
  8.  
  9.  Distribution (pirate or die!)
  10.  -----------------------------
  11.  
  12.  Freely distributable in complete archive with following files included:
  13.  
  14.  SaveNames.c         - source code
  15.  SaveNames.c.info    - source icon
  16.  SaveNames.doc       - this documentation
  17.  SaveNames.doc.info  - documentation icon
  18.  SaveNames.man       - this documentation in UNIX's man format
  19.  SaveNames           - Amiga executable
  20.  SaveNames.info      - Amiga executable icon
  21.  SD!.displayme       - our BBS info
  22.  
  23.  
  24.  Disclaimer (as always :)
  25.  ------------------------
  26.  
  27.  No responsibility or liability will be accepted for any damage that
  28.  may appear to have resulted from use of this program. All use is at
  29.  your own risk. The software is provided "as is" without any warranty
  30.  implied or otherwise to the fitness or accuracy of the software and
  31.  documentation. The author reserves the right to update the software
  32.  and/or documentation without notice.
  33.  
  34.  
  35.  Usage (what is it!?)
  36.  --------------------
  37.  
  38.  Some people (like me) are forced to use pee-cee machines to transfer
  39.  files from internet to my Amiga (it doesn't mean I've bought a pc
  40.  for my own! I use (big word:) it only at my technical university).
  41.  As you all know, no one needs more chars to name his files than 8.3,
  42.  which seems to be a 'professional filename format'. Any other, longer
  43.  names are obsolete and should be forbidden. Unfortunately both Amiga
  44.  and Unix based machines use longer names for their files, so
  45.  transfering files between those platforms via pc causes 90% of name
  46.  (mainly dots :) to be eaten by pc. So I decided to cure this.
  47.  SaveNames is the medicine against. What does it do? Lets say, you want
  48.  to transfer some files stored in directory 'MyFiles' on your Unix
  49.  account to Amiga via pc floppies. Files use 'obsolete' names:
  50.  
  51.                      kickstart
  52.                      KICKdisk.info
  53.                      kickstart.info
  54.  
  55.  So before you start to copy them to disk type:
  56.  
  57.                      SaveNames C MyFiles
  58.  
  59.  and names of all files in this directory are converted ('C' means
  60.  'CODE' and may be lowercase or mixedcase) to less than 8 chars (suffix
  61.  'PCP' (pc protection :) will also be added to allow you easily detect
  62.  those files, or automate decoding e.g. via DOpus FileClass. If you use
  63.  DOpus set class checking to: "MATCHNAME WFMHFile.idx OR MATCHNAME #?.pcp"
  64.  and operation to "(AmigaDos) SaveNames D {s}" and you will decode files
  65.  by doubleclick.). Phew, you said? No big deal? pc does it itself! Bet it
  66.  doesn't. If you look in your 'MyFiles' drawer you'll find the new file
  67.  named 'WFMHFile.idx' looking like that:
  68.  
  69.                      7204094 kickstart
  70.                      720704c KICKdisk.info
  71.                      72085c4 kickstart.info
  72.  
  73.  Got it? Yes! Those data are used to restore filenames after whole
  74.  transfer on destination machine. How to do this? Copy transfered files
  75.  from pc disks to one directory on your Amiga disk (e.g. 'MyFilesToo')
  76.  and type:
  77.  
  78.                      SaveNames D MyFilesToo
  79.  
  80.  This time command 'D' means 'Decode'. Program opens file index
  81.  described below and renames all known (stored in index) files back
  82.  to theirs original names. Simple? Yes, it is. And it works too!
  83.  
  84.  NOTES: Command 'D' has special, expanded mode, activating by '-'
  85.         as command prefix: '-D'. See 'Technical Info' chapter to find
  86.         out what this feature is for.
  87.  
  88.         While names coding SaveNames shows you estimated number of disks
  89.         you will need to store all your crypted files on. If you want
  90.         do this calculation without main code process use '-C' command
  91.         instead of 'C'
  92.  
  93.  Requirements
  94.  ------------
  95.  
  96.  Something with Intel outside, few bytes of free memory, files to eat,
  97.  2 busty babes and 1 big beer.
  98.  
  99.  
  100.  Technical info (sounds soooo wise... :)
  101.  ---------------------------------------
  102.  
  103.  Portability is base idea of this project, so SaveNames is written in
  104.  plain ANSI C and may be simply compiled on any machine. If you find any
  105.  problems, let me know! And do not compile it on pc - it doesn't have any
  106.  sense... :)
  107.  
  108.  Unfortunately small changes, as always, have to be done before you run
  109.  the compiler, so look into the source, and select your platform (for
  110.  now AMIGA, UNIX (being honest IRIX) and LINUX is checked and supported.
  111.  If you port it to Mac world let me know and send changes to me (in this
  112.  case please do only small GUI). AMIGA side was tested on my A4000, UNIX
  113.  platform was tested on SILICON GRAPHICS' IRIS INDIGO and HP. LINUX side
  114.  was tested on... LINUX side :-)
  115.  
  116.  Name encoding is done in two passes. 1st pass - scanning directory
  117.  and building coded names, 2nd pass renaming files and writting
  118.  index file. It has to be done this way, because scanning directory
  119.  while it is changing, may (and in 99% it does) put the program in the
  120.  infinite loop. Sometimes we may also miss some files. Decoding is done
  121.  in one pass.
  122.  
  123.  Starting to decode, program tries to read index file first. First it
  124.  tries to open file named 'WFMHFile.idx'. If file couldn't be found,
  125.  it tries to open file again, with name in lowercase and if it fails
  126.  to, the last try use uppercased name. This is important mainly for
  127.  Unix side, because Unix is case-sensitive. So if you transferred
  128.  your files via pc, the names may be 'fixed' to lower or uppercase.
  129.  While decoding, program may do the same trick with files to decode,
  130.  but this feature is defaulty off, which means that only one try is
  131.  attemped, and filenames are supposed to be exactly the same as while
  132.  coding. Use '-D' instead of 'D' to turn this mode on.
  133.  
  134.  You may convert as many file names as you wish, because there's no
  135.  static arrays, but dynamicaly build list. You are only limited by your
  136.  memory. To code 1000 names you will need, on Amiga, about 266KB. Why
  137.  only 266KB? Because every name is stored in a list's entry containing
  138.  pointer to next entry (on 32bit machines it takes 4 bytes), converted
  139.  name (12 chars + trailing zero) and original file name. The size of last
  140.  entry depends on your system. In your system includes, you will find
  141.  definition of MAXNAMELEN, which limits max length of filename. On Amiga
  142.  it's set to 255 chars. For now it's too much, because you cannot use names
  143.  longer than 30 chars (because there's no more free bytes on disk block).
  144.  So if you are REALLY out of memory, you may change this by hand (see
  145.  included source). Safe value is 108, because system structure
  146.  FileInfoBlock reserves exactly 108 bytes for filename. You may save then
  147.  few bytes. E.g. for those 1000 files mentioned above, with MAXNAMELEN
  148.  set to 30 you will save 248KB, with MAXNAMELEN set to 108, only :) 145
  149.  KB but think what are you doing! You probably never code more than 100
  150.  names in one session and you surely do not use A1000 with 256 KB RAM. So
  151.  better leave MAXNAMELEN alone...
  152.  
  153.  You may ask: How do you code filenames to those weird numbers, pal?
  154.  I answer: I do not code it at all! I'm just copying file's own INode
  155.  (it's kind of FileHandle on Unix machines). Because all filesystems
  156.  use almost the same algorithms, it also use INodes without any tricks
  157.  (maybe pc does it different, but who cares pc?). Sometimes it is
  158.  called INode, sometimes FileHandle and sometimes BlahBlahBlah, but
  159.  it always means the same - almost unique number belongs to file.
  160.  On Amiga side I could use GetUniqueID() from utility.library, but
  161.  it is available under OS3.0 and newer and, what is more important,
  162.  generates only 4294967295 unique numbers. That's all.
  163.  
  164.  
  165.  Bugs (eep...)
  166.  -------------
  167.  
  168.  Program doesn't recognize if name belongs to directory or to file and
  169.  treats all the same. For now, it also can't scan directories
  170.  recursively. Solution: do not create subdirs in drawer you want
  171.  SaveNames to process.
  172.  
  173.  There may appear some problems if you will have two files in the dir,
  174.  being in fact links to other file. In this case INode will be the
  175.  same. Solution: use proper file instead of its shadows.
  176.  
  177.  You must _not_ have file named 'WFMHFile.idx' in your drawer, because
  178.  while encoding/decoding it's written/read sequentially. So while
  179.  encoding it may be overwriten (but not if it is 1st file
  180.  in directory :). While decoding it will be skipped, because of
  181.  already opened (being in use) file with the same name. Solution:
  182.  rename your file :)
  183.  
  184.  On Amiga side it doesn't work when called from WB. If I find some spare
  185.  time I maybe add this, but I am not quite sure it's really needed.
  186.  
  187.  If you have transferred this archive from Unix account to your
  188.  machine via pc, you have probably noticed that few letters have been
  189.  eaten.. You should use... SaveNames to avoid it! :)
  190.  
  191.  Some older compilers requires the function to be declared in old C&R
  192.  style (see the source if you don't know what it's about). If you are
  193.  own such a compiler, simply uncommet the OLD_STYLE definition befor
  194.  you start to compile the program.
  195.  
  196.  
  197.  Future plans (wow!)
  198.  -------------------
  199.  
  200.  If someone finds a reason to decode single files too, I will add this
  201.  feature on request, bacause it's easy to do... :)
  202.  
  203.  I also may add WB handling, but I don't think anybody needs this.
  204.  
  205.  Recursive directory scanning.
  206.  
  207.  
  208.  History (what has happen to the Sherlock Holmes in the past)
  209.  ------------------------------------------------------------
  210.  
  211.   * v1.0  -  Initial release
  212.              Worldwide distribution
  213.              SaveNames-mania....
  214.  
  215.   * v1.1  -  WARNING: Internal format of the 'WFMHFile.idx'
  216.              has been changed! Better decode all old stuff
  217.              before you install this release!
  218.  
  219.              Changes:
  220.  
  221.           -  LINUX and gcc differences and needs supported
  222.           -  Unnecessary %ld's replaced by %d's
  223.           -  SaveNames could not find the index file on Unix
  224.               side if its name was 'processed' by pc (see doc)
  225.  
  226.              Reported by Niklas Edmundsson
  227.  
  228.           -  Added old C&R function declaration for older compilers
  229.               (this feature is switchable and defaulty is off)
  230.           -  SaveNames will not remove 'WFMHFile.idx' index file
  231.               if restoring was not 100% successed
  232.  
  233.              Sugested by Konrad Dubiel
  234.  
  235.   * v1.2  -  Expand decoding mode added (see 'Technical Info').
  236.           -  Solved problems with names contain spaces (this was
  237.               the main reason I've changed the index file format).
  238.           -  SaveNames can now calculate number of disks you will
  239.               need to store contents of your dir on floppies
  240.               (both for Amiga and pc disks) and number of bytes
  241.               left free on the last diskiette.
  242.           -  New command '-C' ('-COUNT') added, which scans given
  243.               directory and counts total length of files and
  244.               floppy disk usage (while coding, those information
  245.               will also be shown).
  246.           -  Source slightly rewritten.
  247.  
  248.   * v1.3  -  Small code improvements (it's now even more portable :-)
  249.           -  Enforcer hit removed
  250.  
  251.  
  252.  Author (it's me, it's me)
  253.  -------------------------
  254.  
  255.  Marcin Orlowski
  256.  ul. Radomska 38
  257.  71-002 Szczecin
  258.  Poland
  259.  
  260.  E-Mail: carlos@felix.univ.szczecin.pl
  261.  WWW   : dedal.univ.szczecin.pl/~carlos/carlos.html
  262.  
  263.  FidoNet:       Marcin Orlowski@2:481/22.2
  264.  GlobalNet:     Marcin Orlowski@52:4800/6
  265.  
  266.  
  267. --------------------- C O M M E R C I A L    B R E A K --------------------
  268.  
  269.       ______ __   __
  270.      / ____//_/  / /            Find your way to the smallest & slowest
  271.     / /___ __   / /  __  __ ______ _____
  272.    /___  // /  / /  / / / // ____// .__/   BBS in central Europe !!!
  273.   ____/ // /_ / /_ / /_/ // __/_ / /
  274.  /_____//___//___/ \____//_____//_/           W.F.M.H. support
  275.                                                                  __
  276.                        ____       GlobalNET: 52:4800/6       __ / /
  277.   +48 91 540431       / __ \        FidoNET: 2:481/22.2     / / \/
  278.                      / / / /_____ ______ ______ _   _      / /   ______
  279.  24 Hours / Day     / / / // .__// ____// __  // \_/ \    /_/   / ____/
  280.                    / /_/ // /   / __/_ / __  // /__/ /   __    _\__  /
  281.  1200-19200 bps   /_____//_/   /_____//_/ /_//_/  /_/   /_/   /_____/
  282.  
  283.      Serving on A3000, 2CDTVs, 2A500+, 5 additional CD-ROMs on-line
  284.                For all Amigas, Macs, C64 and Spectrum fans
  285.